Monster Media 1996 #15/Monster Media Number 15 (Monster Media)(July 1996).ISO/prog_pas/xport11.zip/XPORT.DOC

Text File | 1996-04-01 | 21KB | 547 lines

                              ──══ Galaxy 5 ══──
                    Xport Unit for UrDoor Programmers v1.1
                      Copyright (c) 1996 Thomas J. Smith



                                   CONTENTS
     ────────────────────────────────────────────────────────────────────
      Whats New?.......................................................1
      Introduction.....................................................2
      Requirements.....................................................3
      About This Unit..................................................4
      Getting Started..................................................5
      Running Your Xport...............................................6
      Procedure & Function Library.....................................7
     ────────────────────────────────────────────────────────────────────



                                  WHATS NEW?                           1
     ────────────────────────────────────────────────────────────────────
      New in v1.1 is that it should work now! <G> I had added a command
      that does not work with the distributed versions of UrDoor. It was
      a command that I made global within the UrDoor unit (by editing
      the source code), and that procedure I made global is not global
      in the normal versions of UrDoor. Sorry guys/gals! ;>
     ────────────────────────────────────────────────────────────────────


                                INTRODUCTION                           2
     ────────────────────────────────────────────────────────────────────
      The Xport unit is freeware, and remains copyrighted (c) 1996 by
      Thomas J. Smith. I ask for no royalties from any Xports created
      using this unit. UrDoor, and the FileLock unit are copyrighted
      property of their respective authors. The UrDoor unit is NOT
      included with this archive, however the freeware FileLock unit is
      included. Refer to UrDoor's documentation for information on
      registering the UrDoor unit with the author, Kenneth Bledsoe.
     ────────────────────────────────────────────────────────────────────
      The Xport unit is used in conjunction with the UrDoor door writing
      kit by Kenneth Bledsoe. It will allow UrDoor programmers to write
      Xports quickly and easily! The Xport unit handles all of the drop
      file reading routines, reading & writing the players record, fully
      supports multi node systems by using the FILELOCK.PAS unit, and
      contains many procedures and functions that can be used in your
      Xports!
     ────────────────────────────────────────────────────────────────────


                                 REQUIREMENTS                          3
     ────────────────────────────────────────────────────────────────────
      The Xport unit was written to work with UrDoor for Turbo Pascal 7
      so I am not sure if it will work with TP 6.
     ────────────────────────────────────────────────────────────────────
      Before you can use the Xport unit, you must have URDOOR.TPU,
      XPORT.TPU, FILELOCK.TPU, & NETFILEP.TPU in your units directory,
      or in the directory you will be compiling your Xport(s) in.
     ────────────────────────────────────────────────────────────────────
      And of course you will need Galaxy 5 to test your Xport with! ;>
     ────────────────────────────────────────────────────────────────────


                                ABOUT THIS UNIT                        4
     ────────────────────────────────────────────────────────────────────
      The Xport unit does everything that an Xport is supposed to do.
      Reads the DROPFILE.* file for all of the info required (instead of
      reading a BBS drop file), reads the players info from the
      PLAYERS.DAT file, and reads the info of the current planet that
      the caller is on when he/she enters the Xport.
     ────────────────────────────────────────────────────────────────────
      The Xport unit also writes the players info to the PLAYERS.DAT
      file after your Xport exits, so you NEVER have to access the
      PLAYERS.DAT file, the Xport Unit does it for you! ;> All you have
      to do is make any desired changes to the players record using the
      "Player" variable. For example, to give the player 1,000 krills
      for some reason, just use, "Inc (Player.Money, 1000);" (without
      the quotes of course). You need not record the changes via the
      PLAYERS.DAT file, as the Xport unit does that upon exit of your
      Xport every time, even thru a call to "Halt" via your Xport,
      and/or any run-time errors that may occur!
     ────────────────────────────────────────────────────────────────────
      The Xport unit also makes use of the same file locking routines
      which G5 uses, via the FileLock unit.
     ────────────────────────────────────────────────────────────────────


                                GETTING STARTED                        5
     ────────────────────────────────────────────────────────────────────
      1) Compile the FILELOCK.PAS unit using the "Build All Units"
         option either by selecting "Compile|Build" from within the
         IDE, or by using the /B option for the command line compiler.

      2) Move all *.TPU files to your units directory. Usually TP\UNITS

      3) In your Xports uses statement, include the following units,
         UrDoor, Xport, FileLock. For example,
         Uses UrDoor, Xport, FileLock;

      4) As the VERY first statement of your Xport, name your Xport
         with the UrDoor variable, DoorName (DoorName := 'My Xport';).

      5) The next statement MUST call the "Init_Xport" procedure
         (Init_Xport;). This procedure initializes the Xport unit, and
         reads in all of the info of the player using the Xport,
         including his/her current planet.
     ────────────────────────────────────────────────────────────────────
      The only exception to step 4, is if you install your own exit
      procedure, then put the statements that set up your exit procedure
      as the very first statements in your program. Please note that the
      Xport unit installs its own exit procedure that writes changes to
      the players file in case of a crash or unexpected halt of the
      Xport, but this need not concern you, as it will not interfere
      with your own exit procedures.
     ────────────────────────────────────────────────────────────────────


                              RUNNING YOUR XPORT                       6
     ────────────────────────────────────────────────────────────────────
      Here is the REQUIRED command line to run your Xport that you must
      put in the XPORTS.DAT file located in Galaxy 5's home directory,

      D:\GALAXY5\MYXPORT\MYXPORT.EXE ~UD~ TRUE ~UB~ ~UF~ ~UL~ ~UC~ ~UN~

      replacing MYXPORT with the directory location of your Xport, and
      MYXPORT.EXE with the file name of your Xport. All of the G5 codes
      (~UD~, etc.) MUST be in uppercase!
     ────────────────────────────────────────────────────────────────────
      Here are explanations of each command used on that command line,

      ~UD~ = Shows the Xport where to find the DROPFILE.* file to read
             (the * will be the node number). The Xport unit
             automatically reads the drop file for you, no need for you
             to add a routine to do it yourself! ;>
      TRUE = Set this to TRUE or FALSE for "Keep a log of errors?"
      ~UB~ = Passes the baud rate of the caller.
      ~UF~ = First name of the caller.
      ~UL~ = Last name of the caller.
      ~UC~ = COM port number this caller is on (if local, then this will
             read 0).
      ~UN~ = Node number this caller is on.
     ────────────────────────────────────────────────────────────────────
      When adding your Xport to the XPORTS.DAT file, the first line
      should be the name of your Xport (the way it will be shown to
      callers from the Xports Menu), and the second line should be the
      command line described above. Here is an example,

      A Cool Xport!
      D:\GALAXY5\MYXPORT\MYXPORT.EXE ~UD~ TRUE ~UB~ ~UF~ ~UL~ ~UC~ ~UN~
     ────────────────────────────────────────────────────────────────────


                         PROCEDURE & FUNCTION LIBRARY                  7
     ────────────────────────────────────────────────────────────────────
      This section lists all of the variables, procedures, & functions
      available to you via the Xport unit.
     ────────────────────────────────────────────────────────────────────

                                     VARIABLES
     --------------------------------------------------------------------
      Every one of these variables will already hold a value after you
      call the Init_Xport procedure except for the Enemy records. If you
      wish to read info on an enemy, you must do this yourself.
     --------------------------------------------------------------------

      Player : Player_Info;
     ------------------------
      The Player variable is a record variable  containing all of the
      players info. Refer to the file G5_STRUC.PAS for a run down of all
      of the player record fields that you can manipulate via your
      Xport.


      PlayerFile : File Of Player_Info;
     -----------------------------------
      This refers to the PLAYERS.DAT file located in the subdirectory
      DATA located under the Galaxy 5 home directory. You do not have to
      do anything with this file, as when you call the "WritePlayer"
      function, it will write the players record for you, reflecting any
      changes you may have made.


      Planet : Planet_Info;
     -----------------------
      The planet records variable. Holds info about each of the 5
      planets in the galaxy.


      PlanetFile : File Of Planet_Info;
     -----------------------------------
      Refers to the PLANETS.DAT file also located in the DATA
      subdirectory under the Galaxy 5 home directory.


      Mate : Mate_Info;
     -------------------
      The "Inn Mates" records variable. Contains info on each of the
      mates at each inn that players can flirt with.


      MateFile : File Of Mate_Info;
     -------------------------------
      Refers to the G5_MATES.DAT file located in the DATA subdirectory.


      Enemy : Enemy_Info;
     ---------------------
      Record variable on the enemies that players fight in the
      warfields.


      EnemyFile : File Of Enemy_Info;
     ---------------------------------
      Refers to the ENEMIES.DAT file in the DATA subdirectory. Holds all
      enemy info.


      W_Droid : Array [1..14] Of String[15];
     ----------------------------------------
      Contains the names of each warrior droid for each level.


      SpaceShip, WeaponName, ArmourName : Array [1..10] Of String[20];
     ------------------------------------------------------------------
      These all contain the names of their respective items in an array.


      UserFirst, UserLast : String[25];
     -----------------------------------
      Contains the first and last name of the user respectively.


      BBSName : String[25];
     -----------------------
      The name of the BBS the Xport is being run on.


      IRQ : Byte;
     -------------
      IRQ number the caller is on. If 0, then a fossil driver is being
      used.


      LogErrors : Boolean;
     ----------------------
      Is Log Errors set to true?


      XP_Local : Boolean;
     ---------------------
      Is the Xport being run locally?


      COM : Byte;
     -------------
      COM port number the caller is on. If 0, then Xport is being run
      locally.


      Baud : Integer;
     -----------------
      The callers connected baud rate.


      Caller_From : String[25];
     ---------------------------
      Where the caller is calling from (as grabbed from the BBS drop
      file via the UrDoor unit).


      ANSI : Boolean;
     -----------------
      Set to true if caller has ANSI and/or RIP enabled, else false.


      RIP : Boolean;
     ----------------
      Set to true if caller is calling from a RIP compatible terminal,
      else false. If both ANSI and RIP are false, then caller is calling
      using an ASCII terminal.


      Sec_Level : String[25];
     -------------------------
      Callers security level on the BBS.


      Xport_Dir : String;
     ---------------------
      This variable contains the full path to your Xports directory,
      with NO trailing backslash, or file name of your Xport. Example,
      D:\DOORS\G5\MY_XPORT


      G5_Dir : String;
     ------------------
      Full path of the home Galaxy 5 directory with NO trailing
      backslash. Example, D:\DOORS\G5


      NodeNumber : String[3];
     -------------------------
      Node number the player is on.


      PlayerSex : String[6];
     ------------------------
      The players gender, MALE or FEMALE.


      PlayerHandle : String[20];
     ----------------------------
      The players handle in Galaxy 5.

      CleanMode : Boolean;
     ----------------------
      Holds true if the SysOps has "Allow Getting Laid?" set to NO, else
      reads false.
     ────────────────────────────────────────────────────────────────────

                           PROCEDURES & FUNCTIONS
     --------------------------------------------------------------------

      Function G5YesNo (Default : Char) : Char;
     -------------------------------------------
      Displays a yes no prompt like, [Yes/no], or [yes/No]. The one that
      will be capitalized will be the one that is set as the "Default"
      in the parameter passed. This function will only accept the Y key,
      the N key, or ENTER (which will default to the "Default"
      character). Returns either Y or N.

      Example,
              Var
                 Ch : Char;

              Ch := G5YesNo ('Y');

              This one will default to Yes if the ENTER key is pressed.


      Function G5ReadKey (Default : Char) : Char;
     ---------------------------------------------
      Displays nothing. Returns the uppercase equivelant of the key
      pressed. If ENTER is pressed, then the character returned will be
      the same as that passed as the "Default" parameter.

      Example,
              Var
                 Ch : Char;

              Repeat
                    Ch := G5Readkey('Q');
              Until Ch In ['1','2','3','Q'];

              This example will return Q if the ENTER key is pressed.


      Procedure WriteBar (Color : String);
     --------------------------------------
      Displays a "Galaxy 5 Style" bar at the current cursor position.
      Color is passed as a G5 color code.

      Example,
              WriteBar('~07~');

              This example will write a grey colored bar.


      Procedure G5Enter;
     --------------------
      Displays, ──══ Press Enter ══── centered on the last line of the
      screen if ANSI is true, else it will be shown on the next line
      when called. Only accepts the ENTER key.

      Example,
              G5Enter;


      Procedure G5Pause (Lines : Integer; Fancy : Boolean);
     -------------------------------------------------------
      Displays the <PAUSE> prompt and waits for a key to be pressed.
      Lines is the number of blank lines to write to the screen BEFORE
      the <PAUSE> prompt is shown. If Fancy is set to true, then the
      <PAUSE> prompt will be "drawn" from left to right, and after a key
      has been pressed, it will "erase" from right to left. If Fancy is
      set to false, it will simply show the <PAUSE> prompt, and quickly
      erase it after a key has been pressed.

      Example,
              G5Pause(1, True);

              This will write one blank line to the screen before
              displaying the <PAUSE> prompt, and will use the "fancy"
              version of the prompt.


      Procedure ReadPlanet (Number : Byte);
     ---------------------------------------
      Reads in the planet info of the planet number passed to it. The
      number passed can be 1 through 5. Any higher or lower will show an
      "I/O Error."

      Example,
              ReadPlanet(1);

              This will read in the info on the first planet which you
              can refer to with the "Planet.Variable" record variable.


      Procedure View_Stats;
     -----------------------
      Shows the player his/her stats exactly as it is shown in Galaxy 5.

      Example,
              View_Stats;


      Procedure ReadPlayer (Number : Integer);
     ------------------------------------------
      Reads in the player info of player record number, Number. *NOTE*,
      this procedure really should NEVER be called, as the record of the
      player who is playing will be replaced with the new info! If you
      need to read the info on another player, use the "ReadPlayerTemp"
      procedure.

      Example,
              ReadPlayer (5);

              This will read in the record of the player who has record
              number 5 in the PLAYERS.DAT file.


      ReadPlayerTemp (Number : Integer);
     ------------------------------------
      Same as "ReadPlayer," but reads a temporary record into the
      "Player_Temp" record variable.

      Example,
              ReadPlayerTmp (0);

              This will read the first player in the PLAYERS.DAT file.


      Procedure WritePlayer;
     ------------------------
      Writes the current players record to the PLAYERS.DAT file.

      Example,
              WritePlayer;


      Procedure Read_Enemy (EnemyNum : Integer);
     --------------------------------------------
      Reads the enemys info located at file position EnemyNum in the
      ENEMIES.DAT file. Can then be referred to using the
      "Enemy.Variable" variables.

      Example,
              Read_Enemy (10);

              This will read the 10th enemy record into the "Enemy"
              record variable.


      Procedure Read_Mate (Which : ShortInt);
     -----------------------------------------
      Reads in the mate info of "Which" number. "Which" can be 1 through
      5.

      Example,
              Read_Mate (4);

              Will read in the info of the mates on planet number 4.


      Procedure ReadItems (WhichItems : Byte);
     ------------------------------------------
      This procedure reads in the array of the item number selected in
      "WhichItems." 1 will read in the Ship names, 2 will read in the
      Weapon names, and 3 will read in the Armour names. This is all
      done automatically upon your Xports startup, and should not have
      to be called.

      Example,
              ReadItems (1);

              This will read in the Ship names into the array,
              SpaceShip : Array [1..10] Of String[20];


      Procedure G5Write (S : String);
     ---------------------------------
      Writes the string contained in S to the screen. The string to be
      written can contain any G5 codes available to you, and they will
      be shown correctly. This procedure does NOT add a CR/LF to the end
      of the string!

      Example,
              G5Write ('~03~Press ~0B~ENTER ~03~To Continue...');

              This will write "Press ENTER To Continue..." (without the
              quotes), to the screen. 'Press' & 'To Continue...' would
              be in cyan, and 'ENTER' would be in bright cyan. If the
              caller does not have an ANSI terminal, then the codes are
              simply stripped.


      Procedure G5Writeln (S : String);
     -----------------------------------
      Same as G5Write, except that it sends a carriage return/line feed
      at the end of the string.

      Example,
              G5Writeln ('~03~You Suck!');


      Procedure FileError (Number : Byte);
     --------------------------------------
      Shows the caller a message that looks like,
      "** BLAST IT! **  File is missing!" then calls a <PAUSE> prompt.
      Can be used when a required file is not found. The "Number"
      variable tells the procedure how many blank lines to write to the
      screen BEFORE the "BLAST IT" message is shown.

      Example,
              FileError (1);

              This will write one blank line to the screen, then display
              the "BLAST IT" message, etc.


      Procedure IoError (Number : Byte);
     ------------------------------------
      Exactly the same as the FileError procedure, except this one tells
      the caller there was an I/O error reading a file.

      Example,
              IoError (1);

              Writes one blank line to the screen, then shows the caller
              the message, "*** I/O ERROR ***" then calls a <PAUSE>
              prompt.



   -THE END-